﻿//-----------------------------------------------------------------------------------------
// <copyright file="Orientation.cs" company="Jakub Florczyk (www.jakubflorczyk.pl)">
//      Copyright © 2009 Jakub Florczyk (www.jakubflorczyk.pl)
//      http://samsungmobilesdknet.codeplex.com
// </copyright>
//-----------------------------------------------------------------------------------------

namespace SamsungMobileSDKNET
{
    using System.Runtime.InteropServices;

    /// <summary>
    /// Function signature for orientation event handlers.
    /// </summary>
    /// <param name="position">Position of display.</param>
    public delegate void OrientationEventHandler(OrientationPosition position);

    /// <summary>
    /// Indicates position of the main display of the device.
    /// </summary>
    /// <remarks>
    /// Face up and face down orientations are when the phone is within a few degrees of horizontal position.
    /// <br/>
    /// Portrait and landscape positions are detected when the phone is held at roughly a 30 degree or greater angle.  Please see the Programming Guide for illustrations of the position states.
    /// </remarks>
    public enum OrientationPosition
    {
        /// <summary>
        /// Position face up.
        /// </summary>
        FaceUp,

        /// <summary>
        /// Position face down.
        /// </summary>
        FaceDown,

        /// <summary>
        /// Position landscape.
        /// </summary>
        Landscape,

        /// <summary>
        /// Position reverse landscape.
        /// </summary>
        ReverseLandscape,

        /// <summary>
        /// Position portrait.
        /// </summary>
        Portrait,

        /// <summary>
        /// Position reverse portrait.
        /// </summary>
        ReversePortrait,

        /// <summary>
        /// Position undefined.
        /// </summary>
        Undefined
    }

    /// <summary>
    /// Samsung Orientation API.
    /// </summary>
    /// <remarks>
    /// The Orientation API is a service-level API that provides a centralized orientation service for all applications. This API enables applications to register handlers associated with phone movements.
    /// <br/>
    /// This API is implemented by a centralized polling mechanism for effective CPU utilization.
    /// </remarks>
    public class Orientation
    {
        /// <summary>
        /// Gets the current orientation state.
        /// </summary>
        /// <param name="state">A pointer to the position state.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorCannonActivateServer"/> if the sensor server cannot be started
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiOrientationGetState")]
        public static extern ResultCode GetState(
            [Out] out OrientationPosition state);

        /// <summary>
        /// Registers a handler to be called when the device orientation changes to the orientation specified in state.
        /// <br/>
        /// Only one handler per process can be registered for each device orientation. Subsequent registrations replace the previous handler associated with that device orientation.
        /// </summary>
        /// <param name="state">The orientation state.</param>
        /// <param name="handler">A callback function.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is NULL or invalid
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorCannonActivateServer"/> if the sensor server cannot be started 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiOrientationRegisterOnStateHandler")]
        public static extern ResultCode RegisterOnStateHandler(
            [In] OrientationPosition state,
            [In] OrientationEventHandler handler);

        /// <summary>
        /// Unregisters the handler associated with the given state by a previous call to the <see cref="M:SamsungMobileSDKNET.Orientation.RegisterOnStateHandler"/> function. It does not affect a handler registered by the <see cref="M:SamsungMobileSDKNET.Orientation.RegisterOnChangeHandler"/> function.
        /// </summary>
        /// <param name="state">The orientation state.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is invalid
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorCannonActivateServer"/> if the sensor server cannot be started
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiOrientationUnregisterOnStateHandler")]
        public static extern ResultCode UnregisterOnStateHandler(
            [In] OrientationPosition state);

        /// <summary>
        /// Registers a handler to be called whenever the orientation is changed. The handler is called even when the device enters the SMI_ORIENTATION_UNDEFINED state.
        /// </summary>
        /// <param name="handler">A callback function.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorCannonActivateServer"/> if the sensor server cannot be started
        /// </returns>
        /// <remarks>
        /// Only one OnState handler per process can be registered. Subsequent registrations replace the previous OnState handler.
        /// </remarks>
        [DllImport(Common.DllName, EntryPoint = "SmiOrientationRegisterOnChangeHandler")]
        public static extern ResultCode RegisterOnChangeHandler(
            [In] OrientationEventHandler handler);

        /// <summary>
        /// Unregisters the handler associated by a previous call to the <see cref="M:SamsungMobileSDKNET.Orientation.RegisterOnChangeHandler"/> function. It does not affect handlers registered by the <see cref="M:SamsungMobileSDKNET.Orientation.RegisterOnStateHandler"/> function.
        /// </summary>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorCannonActivateServer"/> if the sensor server cannot be started
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiOrientationUnregisterOnChangeHandler")]
        public static extern ResultCode UnregisterOnChangeHandler();
    }
}
